eraro
Create JavaScript Error objects with code strings, context details, and templated messages.
For use in library modules to generate contextual errors with useful
meta data. Your library module can throw or pass (to a callback) an
Error object that has additional properties, such as a code, that
can be used for programmatic inspection by client code that uses your
library.
If you're using this module, feel free to contact me on twitter if you have any questions! :) @rjrodger
Quick example
var error = require('eraro')({package:'mylib'})
throw error('code_string')
throw error('code_string', 'Message text.')
throw error('code_string', 'Message text.', {foo:1, bar:2})
var ex = new Error('Another message.')
throw error(ex,'code_string',{zed:3})
In all these cases, the Error object will have a code`` property with value
"code_string"`.
Install
npm install eraro
There's an npm module page for eraro.
Usage
Use this module when you are writing a library that will be used by
application code. It allows your library to generate informative error messages.
The module itself is a generator function (taking options) that
returns the error-creating function that you will actually use. Thus
the most common way to use eraro is to require and call immediately:
var error = require('eraro')({package:'mylib'})
The error
function can then be used in your library code. The
error
function generates Error
objects, which can be thrown or used in callbacks:
throw error('code1')
function doStuff (input, callback) {
if (bad(input)) return callback(error('code2'));
}
The package
option is normally the name of your library. That is, the value
of the name
property in package.json
. The generated Error object will
have two properties to define the package: package
, a string that is
the name of the package, and also a boolean, the name of the package itself.
This lets you check for the type of error easily:
var error = require('eraro')({package:'mylib'})
var err0 = error('code0')
"mylib" === err0.package
err0.mylib
Error details
You can supply additional contextual details for debugging or other
purposes. These are placed inside the details property of the
generated Error:
var error = require('eraro')({package:'mylib'})
var err0 = error('code0', {foo: 'FOO', bar: 'BAR'})
"FOO" === err0.details.foo
"BAR" === err0.details.bar
Error codes and message templates
To provide consistent error messages to your users, you can define a set of message templates, keyed by code:
var error = require('eraro')({package: 'mylib', msgmap: {
code0: "The first error, foo is <%=foo%>.",
code1: "The second error, bar is <%=bar%>.",
}})
When you specify a code, and details, these are inserted into the message (if any) associated with that code:
var err0 = error('code0',{foo: 'FOO', bar: 'BAR'})
"mylib: The first error, foo is FOO." === err0.message
The message templates are underscorejs templates
with the default settings.
If you specify a message directly, this is also interpreted as a template:
var err0 = error('code2',
'My custom message, details: <%=util.inspect(zed)%>',
{zed: {a: 1, b: 2}})
"mylib: My custom message, details: { a: 1, b: 2 }" === err0.message
The returned Error object
The returned Error object has the following additional properties:
code
: String; the code stringpackage
: String; the package namepackage-name
: Boolean (true); a convenience marker for the packagemsg
: String; the generated message, may differ from original exception message (if any)details
: Object; contextual details of errorcallpoint
: String; first line of stacktrace that is external to eraro and calling module
You can pass in an existing Error object. The additional properties
will be added to it, but the original message will be used as the
message template, overriding any matching code message.
Options
When creating an error
function, you can use the following options:
package
: (optional) String; package name to mark Error objectsprefix
: (optional) Boolean/String; If false, then no prefix is used; If not defined, the package name is usedmodule
: (optional) Object; module
object to use as starting point for require
callsmsgmap
: (optional) Object; map codes to message templatesinspect
: (optional) Boolean; If true, util.inspect
is called on values; default: true.
In the Wild
For real-world usage examples, see:
- use-plugin: a utility for providing a plugin interface for extensions to your module
- seneca: a micro-services framework for Node.js